home *** CD-ROM | disk | FTP | other *** search
/ Winzipper / Winzipper_ISO.iso / programming / oracle7 7.2 / DB / UTIL72 / DBMSOFLN.SQL < prev    next >
Encoding:
Text File  |  1995-05-09  |  12.0 KB  |  284 lines
  1. rem 
  2. rem $Header: dbmsofln.sql 7020200.1 95/02/15 18:31:44 cli Generic<base> $ 
  3. rem 
  4. Rem
  5. Rem    NAME
  6. Rem
  7. Rem      dbmsofln.sql - replication offline instantiation package spec
  8. Rem
  9. Rem    NOTES
  10. Rem
  11. Rem      The procedural option is needed to use this facility.
  12. Rem
  13. Rem      This package is installed by sys (connect internal).
  14. Rem
  15. Rem      The repcat tables are defined in catrep.sql and owned by system.
  16. Rem
  17. Rem    DEPENDENCIES
  18. Rem      The snapshot packages rely on the dbms_snaphot package and all it
  19. Rem      relies upon (e.g., dbms_defer)
  20. Rem
  21. Rem      The object generator (dbmsobjg) and the replication procedure/trigger
  22. Rem      generator (dbmsgen) must be previously loaded.
  23. Rem
  24. Rem      Uses dynamic SQL (dbmssql.sql) heavily.
  25. Rem
  26. Rem    USAGE
  27. Rem
  28. Rem    BETA RELEASE DISCLAIMER
  29. Rem    This is a beta release of dbmsofln.sql and, as such, is 
  30. Rem    subject to change. DO NOT use this package in a production environment
  31. Rem    without thorough testing.
  32. Rem
  33. Rem    Use the procedures in this package to instantiate a new master site
  34. Rem    for a replicated schema. The replicated schema does not need to
  35. Rem    remain quiesced while the new site is instantiated, however, DO NOT
  36. Rem    call any DBMS_REPCAT procedures until after completing step 9 below.
  37. Rem
  38. Rem    To perform this method of instantiation, complete the following steps:
  39. Rem
  40. Rem    1.    Create the necessary database links from the new site to each
  41. Rem        existing site, and from each existing site to the new site.
  42. Rem
  43. Rem    2.    At the master definition site, call 
  44. Rem        DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY(SchemaName).
  45. Rem        
  46. Rem    3.    At the master definition site, call
  47. Rem        DMBS_OFFLINE_SCHEMA.BEGIN_INSTANTIATION(SchemaName, NewSite).
  48. Rem
  49. Rem        This ensures that any updates at the existing master sites
  50. Rem        are queued for the new master site.
  51. Rem
  52. Rem    4.    At any site, export the user-defined tables for the replicated 
  53. Rem        schema.
  54. Rem
  55. Rem    5.    At the master definition site, call
  56. Rem        DBMS_OFFLINE_SCHEMA.RESUME_MASTERS(SchemaName, NewSite).
  57. Rem
  58. Rem        This allows non-administrative replication activity to resume 
  59. Rem        at the existing master sites.
  60. Rem
  61. Rem    6.    At the new master site, call
  62. Rem        DBMS_OFFLINE_SCHEMA.BEGIN_LOAD(SchemaName, NewSite).
  63. Rem
  64. Rem        This disables the triggers at the new master site so that your
  65. Rem        changes are not added to the queue when you begin importing
  66. Rem        data at the new site.
  67. Rem
  68. Rem    7.    At the new site, import the tables exported in step 4.
  69. Rem
  70. Rem    8.    At the new site, call
  71. Rem        DBMS_OFFLINE_SCHEMA.END_LOAD(SchemaName, NewSite).
  72. Rem
  73. Rem        This re-enables the triggers that were disabled in step 6.
  74. Rem
  75. Rem    9.    At the master definition site, call
  76. Rem        DBMS_OFFLINE_SCHEMA.END_INSTANTIATION(SchemaName, NewSite).
  77. Rem
  78. Rem        This resumes normal replication activity at the new site.
  79. Rem
  80. Rem    10.    Schedule execution of queues between new master site and 
  81. Rem        existing sites. DO NOT push queues to the new master until you 
  82. Rem        have completed step 9. If the new site is already a part of 
  83. Rem        another replicated environment, you must unschedule
  84. Rem             the execution of the queues to the new site between steps 5 and 9.
  85. Rem
  86. Rem    MESSAGES
  87. Rem
  88. Rem    This section describes the probable cause and suggested action for
  89. Rem    messages that you may encounter when using dbmsofln.sql.
  90. Rem
  91. Rem
  92. Rem    ORA-23430 the replicated schema %s does not exist
  93. Rem    Cause:    The caller has provided the name of a replicated schema that
  94. Rem              is not known at the master site as an argument to a routine
  95. Rem              in offline instantiation of a schema.
  96. Rem     Action:   Check that the replicated schema exists at the master site
  97. Rem               where the user is executing the procedure, and retry the call.
  98. Rem
  99. Rem     ORA-23431 site %s is not the master definition site
  100. Rem     Cause:    The master site where the routine was executing is not the
  101. Rem               master definition site.
  102. Rem     Action:   Find out the master definition site for the replicated schema
  103. Rem               in question, and re-run the routine.
  104. Rem
  105. Rem     ORA-23432 wrong state: %s"
  106. Rem     Cause:    Routine is executing against a replicated schema whose state
  107. Rem               is in the wrong state.
  108. Rem     Action:   Make sure that the replicated schema is in the state given in
  109. Rem               the error message.
  110. Rem
  111. Rem     ORA-23433 master site %s already exists
  112. Rem     Cause:    Trying to instantiate a replicated schema at a master site
  113. Rem               that is already a part of the schema.
  114. Rem     Action:   If you were trying to add this site, do nothing because it
  115. Rem               already exists; otherwise, pick the name of another site,
  116. Rem               and re-run the routine.
  117. Rem
  118. Rem     ORA-23434 executing against wrong master site %s
  119. Rem     Cause:    Caller provides an argument indicating the site against which
  120. Rem               the routine should be executing; trying to execute the 
  121. Rem               routine at a site that is different from that argument.
  122. Rem     Action:   Execute against the correct master site.
  123. Rem
  124. Rem     ORA-23435 malformed master site name %s
  125. Rem     Cause:    Site name as argument to routine is not formed correctly.
  126. Rem     Action:   Please consult the Oracle manuals on how to construct site 
  127. Rem               names.
  128. Rem
  129. Rem     ORA-23436 site %s is not master site
  130. Rem     Cause:    The new site given as an argument to a routine is not a
  131. Rem               master site for the given replicated schema.
  132. Rem     Action:   Execute dbms_offline_schema.begin_instantiation() routine to
  133. Rem               add a new site to the replicated schema.
  134. Rem
  135. Rem     ORA-23437 master site %s not known for replicated schema
  136. Rem     Cause:    The site name given as an argument to a routine is not already
  137. Rem               known to the replicated schema.
  138. Rem     Action: Execute dbms_offline_schema.begin_instantiation() routine to
  139. Rem             add a new site to the replicated schema.
  140. Rem
  141. Rem
  142. Rem    SECURITY
  143. Rem
  144. Rem    MODIFIED   (MM/DD/YY)
  145. Rem     boki       01/09/95 -  merge changes from branch 1.1.710.3
  146. Rem     boki       12/21/94 -  merge changes from branch 1.1.710.1
  147. Rem     boki       01/06/95 -  Tech writer to add explanatory comments on use
  148. Rem     boki       01/06/95 -  Tech writer to add more self-explanatory info
  149. Rem     boki       12/02/94 -  Branch_for_patch
  150. Rem     boki       12/02/94 -  Creation
  151. Rem     boki       12/02/94 -  Creation
  152. Rem     boki       10/28/94  -- Substantial modification of Sandeep's original
  153. Rem                             specification.
  154. Rem
  155.  
  156. ---------------------------------------------------------------------------
  157. CREATE OR REPLACE PACKAGE dbms_offline_schema AS
  158.  
  159.   -------------
  160.   -- TYPE DEFINITIONS
  161.   --
  162.   TYPE SetOfSiteType IS TABLE OF VARCHAR2(256)
  163.      INDEX BY BINARY_INTEGER;
  164.  
  165.   -------------
  166.   -- EXCEPTIONS
  167.   --
  168.  
  169.   nosuchschema EXCEPTION;
  170.     PRAGMA exception_init(nosuchschema, -23430);
  171.     nosuchschema_num NUMBER := -23430;
  172.     nosuchschema_msg VARCHAR2(76) := 'the replicated schema %s does not exist';
  173.  
  174.   notmasterdef EXCEPTION;
  175.     PRAGMA exception_init(notmasterdef, -23431);
  176.     notmasterdef_num NUMBER := -23431;
  177.     notmasterdef_msg VARCHAR2(76) := 'site %s is not the master definition site';
  178.  
  179.   wrongstate EXCEPTION;
  180.     PRAGMA exception_init(wrongstate, -23432);
  181.     wrongstate_num NUMBER := -23432;
  182.     wrongstate_msg VARCHAR(76) := 'wrong state: %s';    
  183.  
  184.   sitealreadyexists EXCEPTION;
  185.     PRAGMA exception_init(sitealreadyexists, -23433);
  186.     sitealreadyexists_num NUMBER := -23433;
  187.     sitealreadyexists_msg VARCHAR2(76) := 'master site %s already exists';
  188.  
  189.   wrongsite EXCEPTION;
  190.     PRAGMA exception_init (wrongsite, -23434);
  191.     wrongsite_num NUMBER := -23434;
  192.     wrongsite_msg VARCHAR2(76) := 'executing against wrong master site %s';
  193.  
  194.   badsitename EXCEPTION;
  195.     PRAGMA exception_init (badsitename, -23435);
  196.     badsitename_num NUMBER := -23435;
  197.     badsitename_msg VARCHAR2(76) := 'malformed master site name %s';
  198.  
  199.   notmastersite EXCEPTION;
  200.     PRAGMA exception_init (notmastersite, -23436);
  201.     notmastersite_num NUMBER := -23436;
  202.     notmastersite_msg VARCHAR2(76) := 'site %s is not master site';
  203.  
  204.   unknownsite EXCEPTION;
  205.     PRAGMA exception_init (unknownsite, -23437);
  206.     unknownsite_num NUMBER := -23437;
  207.     unknownsite_msg VARCHAR2(76) := 'master site %s not known for replicated schema';
  208.  
  209.   -------------
  210.   -- PROCEDURES
  211.   --
  212.  
  213.   -- Effects: Each master site, including the "new_site," knows about all
  214.   --   the other sites for schema "schema_name."  This routine must be run
  215.   --   at the master definition site.
  216.   --   Raises the following exceptions:
  217.   --      nosuchschema:   if "schema_name" does not name a schema known at
  218.   --                      this site
  219.   --      notmasterdef:   if the site this routine is executing at is not the
  220.   --                      master def. site.
  221.   --      sitealreadyexists:  if "new_site" is already part of the schema
  222.   --              "schema_name"
  223.   --      wrongstate:     if master def site is not in Quiesced state
  224.   --      badsitename:    if "new_site" is a malformed site name
  225.   PROCEDURE begin_instantiation (schema_name VARCHAR2,
  226.                                  new_site VARCHAR2);
  227.  
  228.   -- Effects: For "schema_name" resume normal activity for all master sites 
  229.   --   excluding "new_site."  This routine must be executed at the
  230.   --   master definition site.
  231.   --   Raises the following exceptions:
  232.   --      nosuchschema:   if "schema_name" does not name a schema known at
  233.   --                      this site
  234.   --      notmasterdef:   if the site this routine is executing at is not the
  235.   --                      master def. site.
  236.   --      badsitename:    new_site is a malformed name
  237.   --      wrongstate:     if master def site is not in Quiesced state
  238.   --      unknownsite:    "new_site" is unknown to "schema_name"
  239.   PROCEDURE resume_masters (schema_name VARCHAR2,
  240.                           new_site VARCHAR2);
  241.  
  242.   -- Effects: For schema "schema_name" this routine integrates each site in
  243.   --   "new_sites" into the set of existing sites.  When the routine returns
  244.   --   normally, all sites can communicate with each other.  This routine 
  245.   --   must be executed at the master definition site.
  246.   --   Raises the following exceptions:
  247.   --      nosuchschema:   if "schema_name" does not name a schema known at
  248.   --                      this site
  249.   --      notmasterdef:   if the site this routine is executing at is not the
  250.   --                      master def. site.
  251.   --      badsitename:    site name is malformed
  252.   --      unknownsite:    site "new_site" is not known to schema "schema_name".
  253.   --      wrongstate:     if master def site is not in Quiesced state
  254.   PROCEDURE end_instantiation (schema_name VARCHAR2,
  255.                        new_site VARCHAR2);
  256.  
  257.   -- Effects: Starts the instantiation of "schema_name" at site "new_site." 
  258.   --    This new site is readied for loading of user-defined tables when routine
  259.   --    returns normally.  
  260.   --    Raises the following exceptions:
  261.   --      nosuchschema:   if "schema_name" does not name a schema known at
  262.   --                      this site
  263.   --      badsitename:    "new_site" is a malformed name of a site.
  264.   --      wrongsite:      routine is not executing against site "new_site"
  265.   --      unknownsite:    "new_site" not a master for given schema
  266.   --      wrongstate:     if master def site is not in Normal state
  267.   PROCEDURE begin_load (schema_name VARCHAR2,
  268.                       new_site VARCHAR2);
  269.  
  270.   --  Effects: Ends the instantiation of schema "schema_name" at site "new_site"
  271.   --    and resumes normal activity.
  272.   --   Raises the following exceptions:
  273.   --      nosuchschema:   if "schema_name" does not name a schema known at
  274.   --                      this site.
  275.   --      badsitename:    "new_site" is a malformed name of a site.
  276.   --      wrongsite:      routine is not executing against site "new_site"
  277.   --      unknownsite:    "new_site" not a master for given schema
  278.   --      wrongstate:     if master def site is not in Normal state
  279.   PROCEDURE end_load (schema_name VARCHAR2,
  280.                       new_site VARCHAR2);
  281.  
  282. end;
  283. /
  284.